Getting Image Characteristics16

Format-specific graphics importers always implement GraphicsImportGetImageDescription and may optionally implement the remaining functions in this section.

GraphicsImportGetNaturalBounds

Returns the bounding rectangle of an image.



 
pascal ComponentResult GraphicsImportGetNaturalBounds (GraphicsImportComponent ci,

                     Rect *naturalBounds);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
naturalBounds A pointer to a rectangle structure describing the size of the bounding rectangle for the: image.

DISCUSSION

You can use the GraphicsImportGetNaturalBounds function to determine the native size of the image associated with a graphics importer component. The natural bounds are always zero-based. This is a convenience function that simply calls GraphicsImportGetImageDescription and extracts the width and height fields.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetImageDescription

Returns image description information.



 
pascal ComponentResult GraphicsImportGetImageDescription (

                     GraphicsImportComponent ci,

                     ImageDescriptionHandle *desc);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
desc: Points to a handle to an image description structure.

DISCUSSION

The GraphicsImportGetImageDescription function returns an image description structure containing information such as the format of the compressed data, its bit depth, natural bounds, and resolution. The caller is responsible for disposing of the returned image description handle.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportGetDataOffsetAndSize

Returns the offset and size of the compressed image data within a file.



 
pascal ComponentResult GraphicsImportGetDataOffsetAndSize (

                     GraphicsImportComponent ci,

                     unsigned long *offset,

                     unsigned long *size);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
offset: A pointer to a value describing the byte offset of the image data from the beginning of the data source.
size: A pointer to a value describing the size of the image data in bytes.

DISCUSSION

This function returns the offset and size of the actual image data within the data source. By default, the offset returned is 0 and the size returned is the size of the file. However, some graphics import components will override this function to skip over unneeded information at the beginning or end of the file.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullErr`	-108	Not enough memory available

GraphicsImportValidate

Validates image data for a data reference.



 
pascal ComponentResult GraphicsImportValidate (

                     GraphicsImportComponent ci,

                     Boolean *valid);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
valid: Pointer to a Boolean value. On return, this parameter is set to true if the the graphics importer component can draw the data reference. If the graphics importer component cannot draw the data reference, this parameter is set to false .

DISCUSSION

The GraphicsImportValidate functions allows a graphics importer component to determine if its current data reference contains valid image data. For example, a JFIF graphics importer component might check for the presence of a JFIF marker at the start of the data stream. This function is provided for applications to use to determine what type of image data a particular file may contain. Sometimes a file may not have the correct file type or file extension. In this case, the application will not know which graphics importer component to use. By iterating through all graphics importer components and calling GraphicsImportValidate for each one, it may be possible to locate a graphics importer component that can draw the specified file.

Not all graphics importer components implement this function. A component that does not implement the function will return the badComponentSelector result code. This does not indicate that the file is valid or invalid.

GraphicsImportValidate does not perform an exhaustive check on the file. It is possible for GraphicsImportValidate to claim a data reference is valid but for GraphicsImportDraw to return an error due to bad data.

Format-specific importers that implement the GraphicsImportValidate call should have the canMovieImportValidateFile bit set in their component flags.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified.
`memFullErr`	-108	Not enough memory available
`badComponentSelector`	0x80008002	Component does not support the specified request code

GraphicsImportGetMetaData

Extracts metadata from an image file.



 
pascal ComponentResult GraphicsImportGetMetaData (

                     GraphicsImportComponent ci,

                     void *userData);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
userData: Contains a pointer to a user data structure. The value you pass should have parameter type UserData .

DISCUSSION

This function extracts metadata from an image file and adds it to a user data structure. (Note that userData must already be allocated.) Different image file formats support different kinds of metadata and have different ways of identifying them. For more information about the kinds of metadata extracted by QuickTime's graphics import components, see the QuickTime Image File Format Specification.

You may create a new user data structure by calling NewUserData . Alternatively, you can obtain a pointer to an existing one by calling GetMovieUserData , GetTrackUserData or GetMediaUserData . If the user data passed to GraphicsImportGetMetaData belongs to a movie, track or media, then whatever metadata is extracted will be added to that movie, track or media.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified.
`memFullErr`	-108	Not enough memory available
`badComponentSelector`	0x80008002	Component does not support the specified request code

GraphicsImportDoesDrawAllPixels

Asks whether the graphics importer expects to draw every pixel.



 
pascal ComponentResult GraphicsImportDoesDrawAllPixels (

                     GraphicsImportComponent ci,

                     short *drawsAllPixels);

ci: Specifies the component instance that identifies your connection to the graphics importer component.
drawsAllPixels: A pointer to a value describing the predicted drawing behavior.

DISCUSSION

Some image file formats permit non-rectangular images or images with transparent regions. When such an image is drawn, not every pixel in the boundary rectangle will be changed. The GraphicsImportDoesDrawAllPixels function lets you try to find out whether this will be the case. For instance, you might choose to erase the area behind the image before drawing.

If the graphics import component supports this function, drawsAllPixels will contain one of the following values on return:

`graphicsImporterDrawsAllPixels`	0	Every pixel in the boundary rectangle will be drawn.
`graphicsImporterDoesntDrawAllPixels`	1	Some pixels in the boundary rectangle will not be drawn.
`graphicsImporterDontKnowIfDrawAllPixels`	2	The graphics importer cannot determine whether all pixels will be drawn.

If the graphics import component does not support this function, it will return badComponentSelector . In this case, it is usually safe to assume that the graphics importer will draw all pixels.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified.
`memFullErr`	-108	Not enough memory available
`badComponentSelector`	0x80008002	Component does not support the specified request code